.\" $Id: PAPI_set_event_info.3,v 1.1.2.1 2006/10/25 14:06:26 terpstra Exp $
.TH PAPI_set_event_info 3 "October, 2006" "PAPI Programmer's Reference" PAPI

.SH NAME
PAPI_set_event_info \- set an event's name, description and definition info

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_set_event_info(PAPI_event_info_t *info, int *EventCode, int replace);"
.fi

.SH DESCRIPTION
.B NOTE: This API has been deprecated in PAPI 3.5 pending a data structure redesign.

This function modifies or adds an event to the PAPI preset event table based on the
contents of an even info structure.
This function presently works only to define or modify PAPI preset events.

.SH ARGUMENTS
The following arguments are explicitly passed, or are implicit in the info structure.
.LP
.I EventCode
--  event code returned by the function on success
.LP
.I replace
--  1 to replace an existing event, or 0 to prevent accidental replacement
.LP
.I info
--  structure containing the event information. Relevant fields in this structure are discussed below.
.LP
.I event_code
--  although the value of this event code is not used, the PAPI_PRESET_MASK bit must be set to indicate
that the following event description is for a preset event.
.LP
.I symbol
--  name of the preset event. If the event name is found in the table and
.I replace
is non-zero, the event definition will be replaced. If the names do not match a new entry will be created.
.LP
.I derived
--  a string value indicating whether and how native event terms are combined to form a preset event. 
Possible values include: 

   NOT_DERIVED: Do nothing; only one native event,
   DERIVED_ADD: Add all native events,
   DERIVED_CMPD: Event lives in first counter but takes 2 or more native codes,
   DERIVED_SUB: Subtract all events from the first event specified,
   DERIVED_POSTFIX: Process events based on specified postfix string,

.LP
.I postfix
--  a string value containing postfix operations used only for DERIVED_POSTFIX events. 
.LP
.I short_descr
--  short description of the event
.LP
.I long_descr
--  detailed description of the event
.LP
.I event_note
--  special information or notes about the event
.LP
.I name
--  an array of up to 8 names of native events that make up this preset event. 

.SH RETURN VALUES
On success, the function returns 
.B PAPI_OK.
The EventCode parameter will also be set to the new event code for this event.
On error, a non-zero error code is returned by the function.

.SH ERRORS
.TP
.B "PAPI_EPERM"
You are trying to modify an existing event without specifying 
.I replace.
.TP
.B "PAPI_EISRUN"
You are trying to modify an event that has been added to an EventSet.
.TP
.B "PAPI_EINVAL"
One or more of the arguments or fields of the info structure is invalid.
.TP
.B "PAPI_ENOTPRESET"
The PAPI preset table is full and there is no room for a new event.
.TP
.B "PAPI_ENOEVNT"
The event specified is not a PAPI preset. Usually because the PAPI_PRESET_MASK bit is not set.

.SH EXAMPLE
.LP
.nf
.if t .ft CW
/*Add a note to a custom definition of PAPI_TOT_INS */
PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode)
if (PAPI_get_event_info(EventCode, &info) != PAPI_OK)
  handle_error(1);
strcpy(info.symbol, "MY_TOT_INS");
strcpy(info.note, "This note describes my version of total instructions.");
if (PAPI_set_event_info(&info, EventCode, 0) != PAPI_OK)
  handle_error(1);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI "(3)," 
.BR PAPIF "(3)," 
.BR PAPI_get_event_info "(3)",
.BR PAPI_set_event_info "(3)",
.BR PAPI_event_name_to_code "(3)" 
